Reads part of a resource into memory and work with a small subsection of a large resource.

void ReadPartialResource (
    Handle theResource, 
    SInt32 offset, 
    void *buffer, 
    SInt32 count
);

theResource

A handle to the resource you wish to read.

offset

The beginning of the resource subsection to be read, measured in bytes from the beginning of the resource.

buffer

A pointer to the buffer into which the partial resource is to be read. Your application is responsible for the buffer’s memory management. You cannot use the ReleaseResource function to release the memory the buffer occupies.

count

The length of the resource subsection.

DISCUSSION

This function always tries to read resources from disk. If a resource is already in memory, the Resource Manager still reads it from disk, and the ResError function returns the result code resourceInMemory. If you try to read past the end of a resource or the value of the offset parameter is out of bounds, ResError returns the result code inputOutOfBounds. If the handle in the parameter theResource doesn’t refer to a resource in an open resource fork, ResError returns the result code resNotFound.

You may experience problems if you have a copy of a resource in memory when you are using the partial resource functions. If you have modified the copy in memory and then access the resource on disk using this function, the function reads the data on disk, not the data in memory, which is referenced through the resource’s handle.

When using partial resource functions, you should call the SetResLoad function, specifying FALSE for the load parameter, before you call GetResource. Using the SetResLoad function prevents the Resource Manager from reading the entire resource into memory. Be sure to restore the normal state by calling SetResLoad again, with the load parameter set to TRUE, immediately after you call the GetResource function. Then use ReadPartialResource to read a portion of the resource into a buffer.

If the entire resource is in memory and you want only part of its data, it’s faster to use the Memory Manager function BlockMove instead of the ReadPartialResource function. If you read a partial resource into memory and then change its size, you can use the SetResourceSize function to change the entire resource’s size on disk as necessary

SPECIAL CONSIDERATIONS

This function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.

© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)